Create Task

Create a task and initialize dependency rows

POST /api/boards/{board_id}/tasks

Create Task

cURL

curl --request POST \
  --url https://api.example.com/api/boards/{board_id}/tasks \
  --header 'Content-Type: application/json' \
  --data '
{
  "title": "<string>",
  "description": "<string>",
  "status": "<string>",
  "priority": "<string>",
  "due_at": "<string>",
  "assigned_agent_id": "<string>",
  "created_by_user_id": "<string>",
  "depends_on_task_ids": [
    {}
  ],
  "tag_ids": [
    {}
  ],
  "custom_field_values": {}
}
'

200

{
  "id": "<string>",
  "board_id": "<string>",
  "title": "<string>",
  "description": "<string>",
  "status": "<string>",
  "priority": "<string>",
  "due_at": "<string>",
  "assigned_agent_id": "<string>",
  "created_by_user_id": "<string>",
  "in_progress_at": "<string>",
  "depends_on_task_ids": [
    {}
  ],
  "blocked_by_task_ids": [
    {}
  ],
  "is_blocked": true,
  "tag_ids": [
    {}
  ],
  "tags": [
    {}
  ],
  "custom_field_values": {},
  "created_at": "<string>",
  "updated_at": "<string>"
}

Create a new task on a board with optional dependencies, tags, and custom field values. The task will be validated against dependency rules and custom field requirements.

Path Parameters

board_id · string · required

The UUID of the board to create the task in

Request Body

title · string · required

Task title

description · string

Detailed task description

status · string · default: "inbox"

Initial task status

Allowed values: inbox, in_progress, review, done

priority · string · default: "medium"

Task priority level (e.g., low, medium, high, critical)

due_at · string

ISO 8601 timestamp for task due date

assigned_agent_id · string

UUID of the agent to assign this task to

created_by_user_id · string

UUID of the user creating the task (auto-populated from auth context if not provided)

depends_on_task_ids · array

Array of task UUIDs this task depends on. Dependencies must:

• Exist on the same board
• Not create circular dependency chains
• Not include the task itself

tag_ids · array

Array of tag UUIDs to apply to this task

custom_field_values · object

Key-value pairs for custom field values. Keys must match board-configured custom field definitions.

Response

id · string

Newly created task UUID

board_id · string

Board UUID

title · string

Task title

description · string

Task description

status · string

Task status

priority · string

Task priority

due_at · string

Due date timestamp

assigned_agent_id · string

Assigned agent UUID

created_by_user_id · string

Creator user UUID

in_progress_at · string

Timestamp when task entered in_progress (null for new tasks)

depends_on_task_ids · array

Dependency task UUIDs

blocked_by_task_ids · array

Task UUIDs blocking this task

is_blocked · boolean

Whether task is blocked by dependencies

tag_ids · array

Applied tag UUIDs

tags · array

Tag objects with id, name, and color

custom_field_values · object

Custom field key-value pairs

created_at · string

Creation timestamp

updated_at · string

Last update timestamp

Example Request

curl -X POST "https://api.openclaw.ai/api/boards/123e4567-e89b-12d3-a456-426614174000/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Implement user authentication",
    "description": "Add OAuth2 authentication flow with JWT tokens",
    "status": "inbox",
    "priority": "high",
    "due_at": "2026-03-15T18:00:00Z",
    "depends_on_task_ids": [
      "660e8400-e29b-41d4-a716-446655440001"
    ],
    "tag_ids": [
      "7f6e5d4c-3b2a-1c0b-9a8f-7e6d5c4b3a2f"
    ],
    "custom_field_values": {
      "effort_points": 5,
      "sprint": "Sprint 12"
    }
  }'

Example Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "board_id": "123e4567-e89b-12d3-a456-426614174000",
  "title": "Implement user authentication",
  "description": "Add OAuth2 authentication flow with JWT tokens",
  "status": "inbox",
  "priority": "high",
  "due_at": "2026-03-15T18:00:00Z",
  "assigned_agent_id": null,
  "created_by_user_id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
  "in_progress_at": null,
  "depends_on_task_ids": [
    "660e8400-e29b-41d4-a716-446655440001"
  ],
  "blocked_by_task_ids": [
    "660e8400-e29b-41d4-a716-446655440001"
  ],
  "is_blocked": true,
  "tag_ids": [
    "7f6e5d4c-3b2a-1c0b-9a8f-7e6d5c4b3a2f"
  ],
  "tags": [
    {
      "id": "7f6e5d4c-3b2a-1c0b-9a8f-7e6d5c4b3a2f",
      "name": "backend",
      "color": "#3b82f6"
    }
  ],
  "custom_field_values": {
    "effort_points": 5,
    "sprint": "Sprint 12"
  },
  "created_at": "2026-03-05T14:22:00Z",
  "updated_at": "2026-03-05T14:22:00Z"
}

Error Responses

409 Conflict - Blocked by Dependencies

Returned when creating a task with incomplete dependencies while also assigning it or setting status to non-inbox:

{
  "detail": {
    "message": "Task is blocked by incomplete dependencies.",
    "code": "task_blocked_cannot_transition",
    "blocked_by_task_ids": [
      "660e8400-e29b-41d4-a716-446655440001"
    ]
  }
}

409 Conflict - Dependency Cycle

{
  "detail": "Dependency cycle detected. Remove the cycle before saving."
}

404 Not Found - Missing Dependencies

{
  "detail": {
    "message": "One or more dependency tasks were not found on this board.",
    "missing_task_ids": [
      "660e8400-e29b-41d4-a716-446655440001"
    ]
  }
}

422 Unprocessable Entity - Invalid Custom Fields

{
  "detail": {
    "message": "Unknown custom field keys for this board.",
    "unknown_field_keys": ["invalid_field"]
  }
}

Notes

• Blocked tasks (with incomplete dependencies) cannot be assigned or moved out of inbox status
• Dependencies must exist on the same board and cannot create cycles
• Custom field values are validated against board-specific field definitions
• Required custom fields must have values (or use their default values)
• The board lead agent is automatically notified when a new task is created
• If an agent is assigned, they receive a notification via the gateway